<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>How to use scripts | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="modules-scripting.html" title="Scripting">
<link rel="prev" href="modules-scripting.html" title="Scripting">
<link rel="next" href="modules-scripting-fields.html" title="Accessing document fields and special variables">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="modules-scripting.html">Scripting</a></span>
»
<span class="breadcrumb-node">How to use scripts</span>
</div>
<div class="navheader">
<span class="prev">
<a href="modules-scripting.html">« Scripting</a>
</span>
<span class="next">
<a href="modules-scripting-fields.html">Accessing document fields and special variables »</a>
</span>
</div>
<div class="chapter">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="modules-scripting-using"></a>How to use scripts<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/scripting/using.asciidoc">edit</a>
</h2>
</div></div></div>
<p>Wherever scripting is supported in the Elasticsearch API, the syntax follows
the same pattern:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">  "script": {
    "lang":   "...",  <a id="CO280-1"></a><i class="conum" data-value="1"></i>
    "source" | "id": "...", <a id="CO280-2"></a><i class="conum" data-value="2"></i>
    "params": { ... } <a id="CO280-3"></a><i class="conum" data-value="3"></i>
  }</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO280-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The language the script is written in, which defaults to <code class="literal">painless</code>.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO280-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>The script itself which may be specified as <code class="literal">source</code> for an inline script or <code class="literal">id</code> for a stored script.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO280-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>Any named parameters that should be passed into the script.</p>
</td>
</tr>
</table>
</div>
<p>For example, the following script is used in a search request to return a
<a class="xref" href="search-request-body.html#request-body-search-script-fields" title="Script Fields">scripted field</a>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT my_index/_doc/1
{
  "my_field": 5
}

GET my_index/_search
{
  "script_fields": {
    "my_doubled_field": {
      "script": {
        "lang":   "expression",
        "source": "doc['my_field'] * multiplier",
        "params": {
          "multiplier": 2
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/592.console"></div>
<h3>
<a id="_script_parameters"></a>Script parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/scripting/using.asciidoc">edit</a>
</h3>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">lang</code>
</span>
</dt>
<dd>
Specifies the language the script is written in.  Defaults to <code class="literal">painless</code>.
</dd>
<dt>
<span class="term">
<code class="literal">source</code>, <code class="literal">id</code>
</span>
</dt>
<dd>
Specifies the source of the script.  An <code class="literal">inline</code> script is specified
<code class="literal">source</code> as in the example above. A <code class="literal">stored</code> script is specified <code class="literal">id</code>
and is retrieved from the cluster state (see <a class="xref" href="modules-scripting-using.html#modules-scripting-stored-scripts" title="Stored scripts">Stored Scripts</a>).
</dd>
<dt>
<span class="term">
<code class="literal">params</code>
</span>
</dt>
<dd>
Specifies any named parameters that are passed into the script as
variables.
</dd>
</dl>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<h3>Prefer parameters<a id="prefer-params"></a>
</h3>
<p>The first time Elasticsearch sees a new script, it compiles it and stores the
compiled version in a cache. Compilation can be a heavy process.</p>
<p>If you need to pass variables into the script, you should pass them in as
named <code class="literal">params</code> instead of hard-coding values into the script itself.  For
example, if you want to be able to multiply a field value by different
multipliers, don’t hard-code the multiplier into the script:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">  "source": "doc['my_field'] * 2"</pre>
</div>
<p>Instead, pass it in as a named parameter:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">  "source": "doc['my_field'] * multiplier",
  "params": {
    "multiplier": 2
  }</pre>
</div>
<p>The first version has to be recompiled every time the multiplier changes.  The
second version is only compiled once.</p>
<p>If you compile too many unique scripts within a small amount of time,
Elasticsearch will reject the new dynamic scripts with a
<code class="literal">circuit_breaking_exception</code> error. By default, up to 15 inline scripts per
minute will be compiled. You can change this setting dynamically by setting
<code class="literal">script.max_compilations_rate</code>.</p>
</div>
</div>
<h3>
<a id="modules-scripting-short-script-form"></a>Short script form<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/scripting/using.asciidoc">edit</a>
</h3>
<p>A short script form can be used for brevity. In the short form, <code class="literal">script</code> is represented
by a string instead of an object. This string contains the source of the script.</p>
<p>Short form:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">  "script": "ctx._source.likes++"</pre>
</div>
<p>The same script in the normal form:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">  "script": {
    "source": "ctx._source.likes++"
  }</pre>
</div>
<h3>
<a id="modules-scripting-stored-scripts"></a>Stored scripts<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/scripting/using.asciidoc">edit</a>
</h3>
<p>Scripts may be stored in and retrieved from the cluster state using the
<code class="literal">_scripts</code> end-point.</p>
<p>If the Elasticsearch security features are enabled, you must have the following
privileges to create, retrieve, and delete stored scripts:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
cluster: <code class="literal">all</code> or <code class="literal">manage</code>
</li>
</ul>
</div>
<p>For more information, see <a class="xref" href="security-privileges.html" title="Security privileges">Security privileges</a>.</p>
<h4>
<a id="_request_examples"></a>Request examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/scripting/using.asciidoc">edit</a>
</h4>
<p>The following are examples of using a stored script that lives at
<code class="literal">/_scripts/{id}</code>.</p>
<p>First, create the script called <code class="literal">calculate-score</code> in the cluster state:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _scripts/calculate-score
{
  "script": {
    "lang": "painless",
    "source": "Math.log(_score * 2) + params.my_modifier"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/593.console"></div>
<p>You may also specify a context as part of the url path to compile a
stored script against that specific context in the form of
<code class="literal">/_scripts/{id}/{context}</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _scripts/calculate-score/score
{
  "script": {
    "lang": "painless",
    "source": "Math.log(_score * 2) + params.my_modifier"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/594.console"></div>
<p>This same script can be retrieved with:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _scripts/calculate-score</pre>
</div>
<div class="console_widget" data-snippet="snippets/595.console"></div>
<p>Stored scripts can be used by specifying the <code class="literal">id</code> parameters as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_search
{
  "query": {
    "script_score": {
      "query": {
        "match": {
            "message": "some message"
        }
      },
      "script": {
        "id": "calculate-score",
        "params": {
          "my_modifier": 2
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/596.console"></div>
<p>And deleted with:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">DELETE _scripts/calculate-score</pre>
</div>
<div class="console_widget" data-snippet="snippets/597.console"></div>
<h3>
<a id="modules-scripting-search-templates"></a>Search templates<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/scripting/using.asciidoc">edit</a>
</h3>
<p>You can also use the <code class="literal">_scripts</code> API to store <span class="strong strong"><strong>search templates</strong></span>. Search
templates save specific <a class="xref" href="search-search.html" title="Search API">search requests</a> with placeholder
values, called template parameters.</p>
<p>You can use stored search templates to run searches without writing out the
entire query. Just provide the stored template’s ID and the template parameters.
This is useful when you want to run a commonly used query quickly and without
mistakes.</p>
<p>Search templates use the <a href="http://mustache.github.io/mustache.5.html" class="ulink" target="_top">mustache
templating language</a>. See <a class="xref" href="search-template.html" title="Search Template">Search Template</a> for more information and examples.</p>
<h3>
<a id="modules-scripting-using-caching"></a>Script caching<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/scripting/using.asciidoc">edit</a>
</h3>
<p>All scripts are cached by default so that they only need to be recompiled
when updates occur. By default, scripts do not have a time-based expiration, but
you can change this behavior by using the <code class="literal">script.cache.expire</code> setting.
You can configure the size of this cache by using the <code class="literal">script.cache.max_size</code> setting.
By default, the cache size is <code class="literal">100</code>.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The size of scripts is limited to 65,535 bytes. This can be
changed by setting <code class="literal">script.max_size_in_bytes</code> setting to increase that soft
limit, but if scripts are really large then a
<a class="xref" href="modules-scripting-engine.html" title="Advanced scripts using script engines">native script engine</a> should be considered.</p>
</div>
</div>
<h3>
<a id="modules-scripting-errors"></a>Script errors<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/scripting/using.asciidoc">edit</a>
</h3>
<p>Elasticsearch returns error details when there is a compliation or runtime
exception.  The contents of this response are useful for tracking down the
problem.</p>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.</p>
</div>
</div>
<p>The contents of <code class="literal">position</code> are experimental and subject to change.</p>
</div>
<div class="navfooter">
<span class="prev">
<a href="modules-scripting.html">« Scripting</a>
</span>
<span class="next">
<a href="modules-scripting-fields.html">Accessing document fields and special variables »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
